Создание первого приложения
===========================

В этом разделе мы расскажем, как создать наше первое приложение.
Для создания нового приложения мы будем использовать `yiic` (консольную утилиту), для
генерации кода — `Gii` (мощный веб кодогенератор). Будем считать для удобства,
что `YiiRoot` — это директория, куда установлен Yii, а `WebRoot` — корневая
директория веб-сервера.

Запускаем `yiic` в консоли со следующими параметрами:
~~~
% YiiRoot/framework/yiic webapp WebRoot/testdrive
~~~
> Note|Примечание: При использовании `yiic` на Mac OS,
> Linux или Unix вам может понадобиться изменить права доступа
> для файла `yiic`, чтобы сделать его исполняемым.
> Альтернативный вариант запуска утилиты представлен ниже:
>
> ~~~
> % cd WebRoot
> % php YiiRoot/framework/yiic.php webapp testdrive
> ~~~

В результате в директории `WebRoot/testdrive` будет создан каркас приложения.

Созданное приложение — хорошая отправная точка для добавления необходимого функционала,
так как оно уже содержит все необходимые директории и файлы.
Не написав ни единой строчки кода, мы уже можем протестировать наше первое Yii-приложение, перейдя в браузере по следующему URL:

~~~
http://hostname/testdrive/index.php
~~~

Приложение содержит четыре страницы: главную, страницу «о проекте», страницу обратной связи и страницу авторизации.
Страница обратной связи содержит форму для отправки вопросов и предложений, а страница авторизации
позволяет пользователю аутентифицироваться и получить доступ к закрытой части сайта (см. рисунки ниже).

![Главная страница](first-app1.png)

![Страница обратной связи](first-app2.png)

![Страница обратной связи с ошибками ввода](first-app3.png)

![Страница обратной связи с успешно отправленной формой](first-app4.png)

![Страница авторизации](first-app5.png)


Наше приложение имеет следующую структуру директорий.
Подробное описание этой структуры можно найти в [соглашениях](/doc/guide/basics.convention#directory).

~~~
testdrive/
    index.php                    скрипт инициализации приложения
    index-test.php               скрипт инициализации функциональных тестов
    assets/                      содержит файлы ресурсов
    css/                         содержит CSS-файлы
    images/                      содержит картинки
    themes/                      содержит темы оформления приложения
    protected/                   содержит защищённые файлы приложения
        yiic                     скрипт yiic
        yiic.bat                 скрипт yiic для Windows
        yiic.php                 PHP-скрипт yiic
        commands/                содержит команды 'yiic'
            shell/               содержит команды 'yiic shell'
        components/              содержит компоненты для повторного использования
            Controller.php       класс базового контроллера
            UserIdentity.php     класс 'UserIdentity' для аутентификации
        config/                  содержит конфигурационные файлы
            console.php          файл конфигурации консоли
            main.php             файл конфигурации веб-приложения
            test.php             файл конфигурации функциональных тестов
        controllers/             содержит файлы классов контроллеров
            SiteController.php   класс контроллера по умолчанию
        data/                    содержит пример базы данных
            schema.mysql.sql     схема БД для MySQL
            schema.sqlite.sql    схема БД для SQLite
            testdrive.db         файл БД для SQLite
        extensions/              содержит сторонние расширения
        messages/                содержит переведённые сообщения
        models/                  содержит файлы классов моделей
            LoginForm.php        модель формы для действия 'login'
            ContactForm.php      модель формы для действия 'contact'
        runtime/                 содержит временные файлы
        tests/                   содержит тесты
        views/                   содержит файлы представлений контроллеров и файлы макетов (layout)
            layouts/             содержит файлы представлений макетов
                main.php         общая для всех страниц разметка
                column1.php      разметка для страниц с одной колонкой
                column2.php      разметка для страниц с двумя колонками
            site/                содержит файлы представлений для контроллера 'site'
                pages/           статические страницы
                    about.php    страница «о проекте»
                contact.php      файл представления для действия 'contact'
                error.php        файл представления для действия 'error' (отображение ошибок)
                index.php        файл представления для действия 'index'
                login.php        файл представления для действия 'login'
~~~

Описанный выше генератор может создать файлы, необходимые при работе с
системой контроля версий Git. Приведённая далее команда создаст все необходимые
`.gitignore` (содержимое `assets` и `runtime` не должно оказаться в репозитории)
и `.gitkeep` (важные директории включаем в репозиторий даже если они пустые):

~~~
% YiiRoot/framework/yiic webapp WebRoot/testdrive git
~~~

Ещё одна поддерживаемая система контроля версий — Mercurial. Если вы пользуетесь
ей, передайте третьим параметром `hg`. Данная возможность доступна с версии 1.1.11.


Соединение с базой данных
----------------------
Большинство веб-приложений используют базы данных, и наше приложение не исключение. Для использования базы данных
необходимо объяснить приложению, как к ней подключиться.
Это делается в конфигурационном файле `WebRoot/testdrive/protected/config/main.php`.
Например, так:

~~~
[php]
return array(
	…
	'components'=>array(
		…
		'db'=>array(
			'connectionString'=>'sqlite:protected/data/testdrive.db',
		),
	),
	…
);
~~~

В приведённом выше коде указано, что приложение должно подключиться к базе данных SQLite
`WebRoot/testdrive/protected/data/testdrive.db` как только это понадобится. Отметим, что
база данных SQLite уже включена в сгенерированное приложение. В этой базе имеется только
одна таблица `tbl_user`:

~~~
[sql]
CREATE TABLE tbl_user (
	id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
	username VARCHAR(128) NOT NULL,
	password VARCHAR(128) NOT NULL,
	email VARCHAR(128) NOT NULL
);
~~~

Если вы хотите использовать базу данных MySQL, то вы можете воспользоваться файлом
`WebRoot/testdrive/protected/data/schema.mysql.sql` для её создания.

> Note|Примечание: Для работы с базой данных Yii требуется расширение PHP PDO
и соответствующий драйвер PDO. Для тестового приложения необходимо подключить
расширения `php_pdo` и `php_pdo_sqlite`.

Реализация операций CRUD
------------------------

А теперь самое интересное. Мы бы хотели добавить операции CRUD
(создание, чтение, обновление и удаление) для только что созданной таблицы `tbl_user` —
это часто необходимо при разработке реальных приложений. Вместо ручного написания кода мы
воспользуемся веб кодогенератором `Gii`.

> Info|Информация: Gii доступен, начиная с версии 1.1.2. Ранее для тех же целей
> использовался уже упомянутый `yiic`. Подробнее `yiic` описан в разделе
«[генерация CRUD при помощи yiic shell](/doc/guide/quickstart.first-app-yiic)».


### Настройка Gii

Для того чтобы использовать Gii, нужно отредактировать
[файл конфигурации приложения](/doc/guide/basics.application#application-configuration)
`WebRoot/testdrive/protected/config/main.php`:

~~~
[php]
return array(
	…
	'import'=>array(
		'application.models.*',
		'application.components.*',
	),

	'modules'=>array(
		'gii'=>array(
			'class'=>'system.gii.GiiModule',
			'password'=>'задайте свой пароль',
		),
	),
);
~~~

После этого перейдите по URL `http://hostname/testdrive/index.php?r=gii` и
введите указанный в конфигурации пароль.

### Генерация модели User

После входа зайдите в раздел `Model Generator`:

![Model Generator](gii-model.png)

В поле `Table Name` введите `tbl_user`. В поле `Model Class` — `User`.
Затем нажмите на кнопку `Preview`. Вы увидите новый файл, который будет
сгенерирован. После нажатия кнопки `Generate` в `protected/models` будет создан
файл `User.php`. Как будет описано далее в руководстве, класс модели `User`
позволяет работать с данными в таблице `tbl_user` в стиле ООП.

### Генерация CRUD

После генерации класса модели мы сгенерируем код, реализующий для неё операции CRUD.
Выбираем `Crud Generator`:

![CRUD Generator](gii-crud.png)

В поле `Model Class` вводим `User`. В поле `Controller ID` — `user` (в нижнем регистре).
Теперь нажимаем `Preview` и затем `Generate`. Генерация кода CRUD завершена.

### Доступ к страницам CRUD

Давайте порадуемся нашим трудам, перейдя по следующему URL:

~~~
http://hostname/testdrive/index.php?r=user
~~~

Мы увидим страницу со списком пользователей из таблицы `tbl_user`. Поскольку наша таблица пуста, то записей в ней не будет.
Кликнем по кнопке `Create User` и, если мы еще не авторизованы, отобразится страница авторизации.
В случае успешной авторизации загрузится форма добавления нового пользователя. Заполним её и нажмем кнопку `Create`.
Если при заполнении формы были допущены ошибки, мы увидим красивое сообщение об ошибке.

Вернувшись назад к списку пользователей, мы должны увидеть только что созданного пользователя.
Повторите описанную операцию и добавьте ещё несколько пользователей. Обратите внимание, что при значительном
количестве пользователей для их отображения на одной странице список будет автоматически разбиваться на страницы.
Выполнив вход в качестве администратора (`admin/admin`),
можно увидеть страницу управления пользователями по адресу:

~~~
http://hostname/testdrive/index.php?r=user/admin
~~~

Появится наглядная таблица пользователей. Кликнув на название одного из полей заголовка таблицы,
можно упорядочить записи по значениям соответствующего столбца.
Для просмотра, редактирования или удаления записей можно воспользоваться кнопками в соответствующих строках таблицы.
Также можно переходить на разные страницы, фильтровать результаты и производить поиск по ним.

Всё это не требует написания ни одной строчки кода!

![Страница управления пользователями](first-app6.png)

![Страница добавления нового пользователя](first-app7.png)